Parent | Child | Previous | Next
 
Xbasic

HTTP_DOWNLOAD_BG Function

Syntax

Result as P = http_download_bg(source_url as C, target_file as C)

Arguments

source_urlCharacter

The location of the file to download.

target_fileCharacter

The name of the file to write locally.

Returns

ResultPointer

A dot variable containing the result of the download request, as well as control information regarding the request.

connect_timeoutNumeric

The amount of time, in milliseconds, that the download process will wait for a sucessful connection to the remote server.

ctrlPointer

A pointer with control variables that can be used to monitor and interrupt a long-running download.

bytesNumeric

A running counter of the size of the data downloaded so far.

exitLogical

If set to true, this will cancel the download currently in process.

download_cancelledLogical

Indicates if the download was cancelled, either because of error or user intervention.

download_completeLogical

Indicates if the download completed sucessfully.

headersCharacter

The headers of the HTTP response received from the server, if any.

pParsedURLPointer

A parsed representation of the target_url that was supplied. This will be equivelent to the result of a5_split_url(source_url,.t.)

read_startTime

A timestamp indicating when the download began.

read_timeoutNumeric

The amount of time, in milliseconds, that the download process will wait to receive data from the server. This is not the total download time allowed. It is the amount of time that HTTP_DOWNLOAD_BG() will wait for a server it the server temporarily pauses while sending the response.

reqCharacter

The full HTTP request that has been assembled in order to retrieve the specified source_url.

responseBinary

The full HTTP response received from the server. This value will continue to change as the download progresses, and will not be complete until download_complete is .t.

result_codeCharacter

The HTTP status code from of the server's response, if any.

sockPointer

The underlying TCP socket used for communication with the remote server.

source_urlCharacter

The URL from which the download is being attempted. This will match the source_url value that was passed in to the function.

statusCharacter

A textual description of the result of the download attempt. This status is set to various values as the download progresses.

target_fileCharacter

The file location that will contain the download contents upon completion. This will match the target_file value that was passed in to the function.

timed_out_on_headersLogical

Indicates if the request timed out while waiting for response headers from the server.

Description

Downloads the resource at the specified Source_URL using the HTTP protocol and saves it to Target_File.

Discussion

The HTTP_DOWNLOAD_BG() downloads the resource at the specified Source_URL using the HTTP protocol and saves it to Target_File. The download is performed in the background, using a separate thread. This allows other Xbasic code to continue running. That other Xbasic code can also interact with the background download to monitor it, or even cancel the download, if desired. Once Result.download_complete is .t., target_file will contain the contents of source_url.

HTTP_DOWNLOAD_BG() cannot be used with an https address. Use HTTP_FETCH() instead.

When Result is held on to in your Xbasic code, Result.response includes the full response from the server, even after the downloaded resource has been saved to disk. This means that a copy of the downloaded file is loaded into system memory until your code deletes Result. This may lead to high memory utilization when downloading large files.
When the server responds with a 30* code, HTTP_DOWNLOAD_BG() does not automatically follow the redirect to the new URL. The developer needs to examine Result.download_cancelled, and in the event that it is .t., examine Result.headers to see if the server issued a redirect. If so, a new HTTP_DOWNLOAD_BG() request will need to be constructed to retrieve the new URL.

Example: PDF Download

Download the Alphasports Explained PDF from the Learning center and save to a predetermined location.

http_download_bg("http://downloads.alphasoftware.com/Books/AlphaSports.pdf", "c:\alphasports.pdf")

Example: Checking Results.Status

Demonstration of Result.status changing as the download progresses.

dim Result as p
Result = http_download_bg("http://www.alphasoftware.com/","c:\Temp\alpha.html")

?Result.status
= "Initializing..."

?Result.Status
= "Connecting to server..."

?Result.Status
= "Downloading file..."

?Result.Status
= "Download complete"

Example: Cancelling a Download

Demonstration of cancelling a download

dim Result as p
Result = http_download_bg("http://www.alphasoftware.com/","c:\Temp\alpha.html")

?Result.Status
= "Downloading file..."

Result.ctrl.Exit = .t.

?Result.Status
= "Download cancelled"

?Result.download_complete
= .F.

?Result.download_cancelled
= .T.

See Also